Adding your own code

One of Alpha's great features is that you can write your own functions to do exactly what you want to do. Here is some advice how to do it in a way which makes it as easy as possible to upgrade to a new version of Alpha or HTML mode.

Don't change any of the tcl files unless absolutely necessary. Rather do the following.

• If you're writing new procs put them in either the global prefs file or in the mode specific prefs file.
• If you want to replace a proc in some file you can use the trick described in smarterSource.tcl. If you for example want to change a proc in htmlCustom.tcl create a new file called htmlCustom+.tcl and put the new proc in this file. htmlCustom+.tcl should be put in Alpha's folder in the Preferences folder in your System folder. htmlCustom+.tcl will then automatically be loaded immediately after htmlCustom.tcl. Read the documentation for the Smarter Source package for details. Note that the package Smarter Source has to activated in the packages menu for this to work.
• If you're writing new code for HTML mode don't rely too heavily on existing procs. I can't guarantee that they will do exactly the same thing in future versions.

If you write something which you think is of general interest, please share your code with the rest of the world by sending it to me so I can include it in future versions of HTML mode.

Modifying the menus

If you write some new procs and want to add new menu items to the two HTML menus it can be done easily with a little programming. The method described below can be used to add things to all HTML submenus with a few exceptions.

• It is not possible to add anything to the top level of the menus, only to the submenus.
• The submenu 'Character Entities' can't be changed.
• In the submenu 'Browsers' you can only modify the top part.
• In the submenu 'Character Translation' the two last menu items are added separately, but you can modify the top part.

Each submenu is defined by a variable html<first word in menu name>Sub, which is a list of lists defining the menu items. For example the variable defining the submenu "Home Page Windows" is defined by

set htmlHomeSub {{"" Open...} {"<U<O/V" "Paste URL/Paste Include Tags"} {"" "Refresh Windows"}}

and the variable defining the submenu "Links" is defined

set htmlLinksSub {{"<B<O/A" "Link or Anchor" A} {"<B<O/I" Image IMG}
    {"" Object OBJECT} {"" Sound BGSOUND}}

What are the items in the sublists defining the menu items?

• The first string is the default key binding. For example for Open... it is an empty string, i.e. no key binding and for "Link or Anchor" it is "<B<O/A" which defines the binding ctrl-cmd-A.
• The second item is the menu item text.
• The third optional item is only used for menu items related to an HTML element. The third item is the HTML element in uppercase and is used by CSS mode when it defines its key bindings.

The first thing you should do when you want to modify a submenu is to copy the original definition to your HTML prefs file. You find the original definitions in the files htmlMenu.tcl and hctsmslMenu.tcl. Then you can redefine the variables in your HTML prefs file.

The next thing to do is to rebuild the submenu. That is done by adding a line

htmlRebuildOneMenu "menu name"

to your HTML prefs file.

As an explicit example, these two lines add an item "Close" to the submenu "Home Page Windows"

set htmlHomeSub {{"" Open...} {"" Close} {"<U<O/V" "Paste URL/Paste Include Tags"} {"" "Refresh Windows"}}
htmlRebuildOneMenu "Home Page Windows"

Ok, it is not enough to just add a menu item. You want something to happen when you select it. This can be done automatically if you name the proc you want to be called like this: If you add a menu item "New Menu Item" then name the proc htmlNewMenuItem. This proc should have no arguments. In the above example we would have called the proc htmlClose. In fact, many of the procs called by the menu items in the HTML menus are named in this way, for example there are procs htmlInsertLineBreaks, htmlMakeList, etc. If you add a menu item ending by ... omit the ... in the proc name.